chrome.app.window
Description: |
Use the chrome.app.window API to create windows. Windows
have an optional frame with title bar and size controls. They are not
associated with any Chrome browser windows. See the
Window State Sample for a demonstration of these options.
|
Availability: |
Since Chrome 35.
|
A note on draggable window areas
Windows can be moved by dragging on the default title bar,
but frameless windows do not have that affordance.
The CSS property -webkit-app-region
can be given the values
drag
and no-drag
to allow content of a window
to create draggable areas. Care must be taken when setting a high level
DOM node to drag, any child that is intractable/clickable must be set to
no-drag. E.g.
<div class='title-area'> A draggable area. <div class='title-button'>clickable button</div> </div>
.title-area { -webkit-app-region: drag; } .title-button { -webkit-app-region: no-drag; }
See the Frameless Window Sample as an example.
Summary
Types | |
---|---|
ContentBounds | |
BoundsSpecification | |
Bounds | |
FrameOptions | |
CreateWindowOptions | |
AppWindow | |
Methods | |
create −
chrome.app.window.create(string url, CreateWindowOptions options, function callback)
| |
current −
AppWindow
chrome.app.window.current()
| |
getAll −
array of AppWindow
chrome.app.window.getAll()
| |
get −
AppWindow
chrome.app.window.get(string id)
| |
canSetVisibleOnAllWorkspaces −
boolean
chrome.app.window.canSetVisibleOnAllWorkspaces()
| |
Events | |
onBoundsChanged | |
onClosed | |
onFullscreened | |
onMaximized | |
onMinimized | |
onRestored |
Types
ContentBounds
properties | ||
---|---|---|
integer | (optional) left | |
integer | (optional) top | |
integer | (optional) width | |
integer | (optional) height |
BoundsSpecification
properties | ||
---|---|---|
integer | (optional) left |
The X coordinate of the content or window. |
integer | (optional) top |
The Y coordinate of the content or window. |
integer | (optional) width |
The width of the content or window. |
integer | (optional) height |
The height of the content or window. |
integer | (optional) minWidth |
The minimum width of the content or window. |
integer | (optional) minHeight |
The minimum height of the content or window. |
integer | (optional) maxWidth |
The maximum width of the content or window. |
integer | (optional) maxHeight |
The maximum height of the content or window. |
Bounds
properties | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
integer | left |
This property can be used to read or write the current X coordinate of the content or window. |
|||||||||
integer | top |
This property can be used to read or write the current Y coordinate of the content or window. |
|||||||||
integer | width |
This property can be used to read or write the current width of the content or window. |
|||||||||
integer | height |
This property can be used to read or write the current height of the content or window. |
|||||||||
integer | (optional) minWidth |
This property can be used to read or write the current minimum width of the content or window. A value of |
|||||||||
integer | (optional) minHeight |
This property can be used to read or write the current minimum height of the content or window. A value of |
|||||||||
integer | (optional) maxWidth |
This property can be used to read or write the current maximum width of the content or window. A value of |
|||||||||
integer | (optional) maxHeight |
This property can be used to read or write the current maximum height of the content or window. A value of |
|||||||||
function | setPosition |
Set the left and top position of the content or window.
|
|||||||||
function | setSize |
Set the width and height of the content or window.
|
|||||||||
function | setMinimumSize |
Set the minimum size constraints of the content or window. The minimum width or height can be set to
|
|||||||||
function | setMaximumSize |
Set the maximum size constraints of the content or window. The maximum width or height can be set to
|
FrameOptions
properties | ||
---|---|---|
string | (optional) type |
Frame type: For
|
string | (optional) color |
Allows the frame color to be set. Frame coloring is only available if the frame type is Frame coloring is new in Chrome 36. |
string | (optional) activeColor |
Since Chrome 36.
Allows the frame color of the window when active to be set. Frame coloring is only available if the frame type is Frame coloring is only available if the frame type is Frame coloring is new in Chrome 36. |
string | (optional) inactiveColor |
Since Chrome 36.
Allows the frame color of the window when inactive to be set differently to the active color. Frame coloring is only available if the frame type is
Frame coloring is new in Chrome 36. |
CreateWindowOptions
properties | ||
---|---|---|
string | (optional) id |
Id to identify the window. This will be used to remember the size and position of the window and restore that geometry when a window with the same id is later opened. If a window with a given id is created while another window with the same id already exists, the currently opened window will be focused instead of creating a new window. |
BoundsSpecification | (optional) innerBounds |
Used to specify the initial position, initial size and constraints of the window's content (excluding window decorations). If an Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same bounds property for both the This property is new in Chrome 36. |
BoundsSpecification | (optional) outerBounds |
Used to specify the initial position, initial size and constraints of the window (including window decorations such as the title bar and frame). If an Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same bounds property for both the This property is new in Chrome 36. |
integer | (optional) minWidth |
Deprecated since Chrome 36. Use innerBounds or outerBounds. Minimum width of the window. |
integer | (optional) minHeight |
Deprecated since Chrome 36. Use innerBounds or outerBounds. Minimum height of the window. |
integer | (optional) maxWidth |
Deprecated since Chrome 36. Use innerBounds or outerBounds. Maximum width of the window. |
integer | (optional) maxHeight |
Deprecated since Chrome 36. Use innerBounds or outerBounds. Maximum height of the window. |
enum of "shell" , or "panel" |
(optional) type |
Deprecated since Chrome 69. All app windows use the 'shell' window type Type of window to create.
|
boolean | (optional) showInShelf |
Since Chrome 54. If true, the window will have its own shelf icon. Otherwise the window will be grouped in the shelf with other windows that are associated with the app. Defaults to false. If showInShelf is set to true you need to specify an id for the window. |
string | (optional) icon |
Since Chrome 54. URL of the window icon. A window can have its own icon when showInShelf is set to true. The URL should be a global or an extension local URL. |
string or FrameOptions | (optional) frame |
Frame type: Use of |
ContentBounds | (optional) bounds |
Deprecated since Chrome 36. Use innerBounds or outerBounds. Size and position of the content in the window (excluding the titlebar). If an id is also specified and a window with a matching id has been shown before, the remembered bounds of the window will be used instead. |
enum of "normal" , "fullscreen" , "maximized" , or "minimized" |
(optional) state |
The initial state of the window, allowing it to be created already fullscreen, maximized, or minimized. Defaults to 'normal'. |
boolean | (optional) resizable |
If true, the window will be resizable by the user. Defaults to true. |
boolean | (optional) singleton |
Deprecated since Chrome 35. Multiple windows with the same id is no longer supported. By default if you specify an id for the window, the window will only be created if another window with the same id doesn't already exist. If a window with the same id already exists that window is activated instead. If you do want to create multiple windows with the same id, you can set this property to false. |
boolean | (optional) alwaysOnTop |
If true, the window will stay above most other windows. If there are multiple windows of this kind, the currently focused window will be in the foreground. Requires the Call |
boolean | (optional) focused |
If true, the window will be focused when created. Defaults to true. |
boolean | (optional) visibleOnAllWorkspaces |
Since Chrome 39. If true, and supported by the platform, the window will be visible on all workspaces. |
AppWindow
properties | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
function | focus |
Focus the window. |
|||||||||
function | fullscreen |
Fullscreens the window. The user will be able to restore the window by pressing ESC. An application can prevent the fullscreen state to be left when ESC is pressed by requesting the
Note |
|||||||||
function | isFullscreen |
Is the window fullscreen? This will be true if the window has been created fullscreen or was made fullscreen via the Returns boolean. |
|||||||||
function | minimize |
Minimize the window. |
|||||||||
function | isMinimized |
Is the window minimized? Returns boolean. |
|||||||||
function | maximize |
Maximize the window. |
|||||||||
function | isMaximized |
Is the window maximized? Returns boolean. |
|||||||||
function | restore |
Restore the window, exiting a maximized, minimized, or fullscreen state. |
|||||||||
function | moveTo |
Deprecated since Chrome 43. Use outerBounds. Move the window to the position (|left|, |top|).
|
|||||||||
function | resizeTo |
Deprecated since Chrome 43. Use outerBounds. Resize the window to |width|x|height| pixels in size.
|
|||||||||
function | drawAttention |
Draw attention to the window. |
|||||||||
function | clearAttention |
Clear attention to the window. |
|||||||||
function | close |
Close the window. |
|||||||||
function | show |
Show the window. Does nothing if the window is already visible. Focus the window if |focused| is set to true or omitted.
|
|||||||||
function | hide |
Hide the window. Does nothing if the window is already hidden. |
|||||||||
function | getBounds |
Deprecated since Chrome 36. Use innerBounds or outerBounds. Get the window's inner bounds as a ContentBounds object. Returns ContentBounds. |
|||||||||
function | setBounds |
Deprecated since Chrome 36. Use innerBounds or outerBounds. Set the window's inner bounds.
|
|||||||||
function | isAlwaysOnTop |
Is the window always on top? Returns boolean. |
|||||||||
function | setAlwaysOnTop |
Set whether the window should stay above most other windows. Requires the
|
|||||||||
function | setVisibleOnAllWorkspaces |
Since Chrome 39. Set whether the window is visible on all workspaces. (Only for platforms that support this).
|
|||||||||
Window | contentWindow |
The JavaScript 'window' object for the created child. |
|||||||||
string | id |
The id the window was created with. |
|||||||||
Bounds | innerBounds |
The position, size and constraints of the window's content, which does not include window decorations. This property is new in Chrome 36. |
|||||||||
Bounds | outerBounds |
The position, size and constraints of the window, which includes window decorations, such as the title bar and frame. This property is new in Chrome 36. |
Methods
create
chrome.app.window.create(string url, CreateWindowOptions options, function callback)
The size and position of a window can be specified in a number of different ways. The most simple option is not specifying anything at all, in which case a default size and platform dependent position will be used.
To set the position, size and constraints of the window, use the innerBounds
or outerBounds
properties. Inner bounds do not include window decorations. Outer bounds include the window's title bar and frame. Note that the padding between the inner and outer bounds is determined by the OS. Therefore setting the same property for both inner and outer bounds is considered an error (for example, setting both innerBounds.left
and outerBounds.left
).
To automatically remember the positions of windows you can give them ids. If a window has an id, This id is used to remember the size and position of the window whenever it is moved or resized. This size and position is then used instead of the specified bounds on subsequent opening of a window with the same id. If you need to open a window with an id at a location other than the remembered default, you can create it hidden, move it to the desired location, then show it.
Parameters | |||||
---|---|---|---|---|---|
string | url | ||||
CreateWindowOptions | (optional) options | ||||
function | (optional) callback |
Called in the creating window (parent) before the load event is called in the created window (child). The parent can set fields or functions on the child usable from onload. E.g. background.js:
window.js:
If you specify the callback parameter, it should be a function that looks like this: function(AppWindow createdWindow) {...};
|
current
AppWindow
chrome.app.window.current()
Returns an AppWindow object for the current script context (ie JavaScript 'window' object). This can also be called on a handle to a script context for another page, for example: otherWindow.chrome.app.window.current().
getAll
array of AppWindow
chrome.app.window.getAll()
Gets an array of all currently created app windows. This method is new in Chrome 33.
get
AppWindow
chrome.app.window.get(string id)
Gets an AppWindow with the given id. If no window with the given id exists null is returned. This method is new in Chrome 33.
Parameters | ||
---|---|---|
string | id |
canSetVisibleOnAllWorkspaces
boolean
chrome.app.window.canSetVisibleOnAllWorkspaces()
Since Chrome 42.
Whether the current platform supports windows being visible on all workspaces.
Events
onBoundsChanged
Fired when the window is resized.
addListener
chrome.app.window.onBoundsChanged.addListener(function callback)
Parameters | ||
---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function() {...};
|
onClosed
Fired when the window is closed. Note, this should be listened to from a window other than the window being closed, for example from the background page. This is because the window being closed will be in the process of being torn down when the event is fired, which means not all APIs in the window's script context will be functional.
addListener
chrome.app.window.onClosed.addListener(function callback)
Parameters | ||
---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function() {...};
|
onFullscreened
Fired when the window is fullscreened (either via the AppWindow
or HTML5 APIs).
addListener
chrome.app.window.onFullscreened.addListener(function callback)
Parameters | ||
---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function() {...};
|
onMaximized
Fired when the window is maximized.
addListener
chrome.app.window.onMaximized.addListener(function callback)
Parameters | ||
---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function() {...};
|
onMinimized
Fired when the window is minimized.
addListener
chrome.app.window.onMinimized.addListener(function callback)
Parameters | ||
---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function() {...};
|
onRestored
Fired when the window is restored from being minimized or maximized.
addListener
chrome.app.window.onRestored.addListener(function callback)
Parameters | ||
---|---|---|
function | callback |
The callback parameter should be a function that looks like this: function() {...};
|